---
title: "Authentication"
description: "REST endpoints for authentication and token management"
---

## Exchange Token

Exchange a Supabase JWT token for a MentraOS core token.

<Warning>
This endpoint is used by the mobile app after Supabase authentication.
</Warning>

### Endpoint

<CodeGroup>
```bash Production
POST https://api.mentra.glass/api/auth/exchange-token
```

```bash Development
POST https://devapi.mentra.glass/api/auth/exchange-token
```

```bash Local
POST http://localhost:8002/api/auth/exchange-token
```
</CodeGroup>

### Request Body

```json
{
  "supabaseToken": "eyJhbGciOiJIUzI1NiIs..."
}
```

### Response

Success (200):
```json
{
  "coreToken": "eyJhbGciOiJIUzI1NiIs..."
}
```

Error (400/401):
```json
{
  "error": "No token provided"  // or "Invalid token"
}
```

### Implementation

- **File**: `packages/cloud/src/routes/auth.routes.ts:19-51`
- **Verification**: Uses `SUPABASE_JWT_SECRET` environment variable
- **Token Generation**: Signs with `AUGMENTOS_AUTH_JWT_SECRET`
- **Token Expiry**: No explicit expiry set on core token

### Core Token Structure

The generated coreToken contains:
- `sub`: User ID from Supabase
- `email`: User's email address
- `organizations`: Array of user's organizations
- `defaultOrg`: User's default organization

## Generate Webview Token

Generate a temporary token for webview authentication within apps.

### Endpoint

<CodeGroup>
```bash Production
POST https://api.mentra.glass/api/auth/generate-webview-token
```

```bash Development
POST https://devapi.mentra.glass/api/auth/generate-webview-token
```

```bash Local
POST http://localhost:8002/api/auth/generate-webview-token
```
</CodeGroup>

### Headers

```
Authorization: Bearer <coreToken>
```

### Request Body

```json
{
  "packageName": "com.example.app"
}
```

### Response

```json
{
  "success": true,
  "token": "temp_token_abc123..."
}
```

### Implementation

- **File**: `packages/cloud/src/routes/auth.routes.ts:54-69`
- **Middleware**: `validateCoreToken` - Validates the core JWT token
- **Service**: Uses `tokenService.generateTemporaryToken()`

## Exchange User Token

Exchange a temporary token for user details (called by app backends).

### Endpoint

<CodeGroup>
```bash Production
POST https://api.mentra.glass/api/auth/exchange-user-token
```

```bash Development
POST https://devapi.mentra.glass/api/auth/exchange-user-token
```

```bash Local
POST http://localhost:8002/api/auth/exchange-user-token
```
</CodeGroup>

### Headers

```
Authorization: Bearer <appApiKey>
```

<Note>
The validateAppApiKey middleware extracts the API key from the Authorization header.
</Note>

### Request Body

```json
{
  "aos_temp_token": "temp_token_abc123...",
  "packageName": "com.example.app"
}
```

### Response

Success:
```json
{
  "success": true,
  "userId": "user@example.com"
}
```

Error:
```json
{
  "success": false,
  "error": "Invalid or expired token"
}
```

### Implementation

- **File**: `packages/cloud/src/routes/auth.routes.ts:72-93`
- **Middleware**: `validateAppApiKey` - Validates app API key
- **Service**: Uses `tokenService.exchangeTemporaryToken()`

## Exchange Store Token

Special endpoint for the MentraOS Store webview to get full tokens.

### Endpoint

<CodeGroup>
```bash Production
POST https://api.mentra.glass/api/auth/exchange-store-token
```

```bash Development
POST https://devapi.mentra.glass/api/auth/exchange-store-token
```

```bash Local
POST http://localhost:8002/api/auth/exchange-store-token
```
</CodeGroup>

### Request Body

```json
{
  "aos_temp_token": "temp_token_abc123...",
  "packageName": "org.augmentos.store"
}
```

### Response

```json
{
  "success": true,
  "userId": "user@example.com",
  "tokens": {
    "supabaseToken": "eyJhbGciOiJIUzI1NiIs...",
    "coreToken": "eyJhbGciOiJIUzI1NiIs..."
  }
}
```

### Implementation

- **File**: `packages/cloud/src/routes/auth.routes.ts:96-145`
- **Validation**: Only accepts `packageName: "org.augmentos.store"`
- **Returns**: Both Supabase and core tokens for full authentication

## Hash with API Key

Create a hash using an app's API key (for secure client-side verification).

### Endpoint

<CodeGroup>
```bash Production
POST https://api.mentra.glass/api/auth/hash-with-api-key
```

```bash Development
POST https://devapi.mentra.glass/api/auth/hash-with-api-key
```

```bash Local
POST http://localhost:8002/api/auth/hash-with-api-key
```
</CodeGroup>

### Headers

```
Authorization: Bearer <coreToken>
```

### Request Body

```json
{
  "stringToHash": "data_to_hash",
  "packageName": "com.example.app"
}
```

### Response

```json
{
  "success": true,
  "hash": "sha256_hash_result..."
}
```

### Implementation

- **File**: `packages/cloud/src/routes/auth.routes.ts:148-162`
- **Service**: Uses `appService.hashWithApiKey()`
- **Purpose**: Allows apps to verify data integrity

## Generate Signed User Token

Generate a signed JWT token for webview authentication in apps.

### Endpoint

<CodeGroup>
```bash Production
POST https://api.mentra.glass/api/auth/generate-webview-signed-user-token
```

```bash Development
POST https://devapi.mentra.glass/api/auth/generate-webview-signed-user-token
```

```bash Local
POST http://localhost:8002/api/auth/generate-webview-signed-user-token
```
</CodeGroup>

### Headers

```
Authorization: Bearer <coreToken>
```

### Request Body

```json
{
  "packageName": "com.example.app"
}
```

### Response

```json
{
  "success": true,
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "expiresIn": "10m"
}
```

### Implementation

- **File**: `packages/cloud/src/routes/auth.routes.ts:176-199`
- **Service**: Uses `tokenService.issueUserToken()`
- **Signing**: Uses RSA private key for client-side verification
- **Expiration**: 10 minutes

## Error Codes

| Code | Description |
|------|-------------|
| 400 | Missing required parameters |
| 401 | Invalid or expired token |
| 403 | Forbidden (wrong package name) |
| 500 | Internal server error |

## Security Notes

1. All tokens should be transmitted over HTTPS
2. Core tokens expire after a configured duration
3. Temporary tokens are single-use and expire quickly
4. API keys must be kept secret and never exposed client-side